DocsParameters
Parameters provide a method of passing data into an API request by dynamically adding a value when an API is called from within a process. They can be used in base URLs, action URL paths, headers, request bodies, and when exposed to processes, they are available as inputs for actions in objects and processes when the appropriate API service is selected as a business object.
Two types of parameters can be configured in an API definition, common parameters and action specific parameters. Common parameters are used in all actions and parameters configured at action level are available only to that action.
To use a parameter value in URL paths, headers, and request bodies, enclose parameters in square brackets. For example:
http://staff.database.com/api/[version]/employee/[id]
When a process that uses the associated API definition is run and the parameters are expanded, the URL could become:
http://staff.database.com/api/v2/employee/290054
To use square brackets without referencing a parameter, the text must start with double square brackets. For example, if the request body included:
{
"favourite-colours": [["green", "red", "blue"]
}
When the API is called, the HTTP request includes the square brackets:
{
"favourite-colours": ["green", "red", "blue"]
}
Parameters are applied at the point at which an API is called and values are taken from the API definition if an initial value has been set. However, if the parameter has been exposed and a value has been entered as an input in a process action, this value will be used.
In the following example, two common parameters are configured in the API definition, both with initial values set and both exposed to processes.
The parameters are referenced in the request URL.
An input value for the version parameter is set in an action but not for the id parameter.
When the action runs and the API is called, the id parameter value is taken from the API definition and the version from the action input.
